home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / tools / disk-tools / hdoff / developers.doc < prev    next >
Encoding:
Text File  |  1996-03-06  |  4.5 KB  |  147 lines
  1.  
  2.                          HDOff - Developer`s Note v1.1
  3.                 © 1996 by Gideon Zenz - all rights reserved
  4.  
  5. INTRODUCTION
  6.  
  7. This  is  my  2nd  try  of  the Developer`s Guide for HDOff.  I hope it`s a
  8. little bit better than the 1st version.  New for this, the port`s structure
  9. is also included in a C-version, and also a C example program.
  10.  
  11.  
  12. CHANGES
  13.  
  14. I  decided  to  make  some adjustements on the portstructure!  Note the new
  15. field HD_Reserved, and also that there are now NO BYTE fields!  I hope this
  16. makes programming a bit easier.
  17.  
  18.  
  19. THE PORT
  20.  
  21. HDOff  communicates  with  the  world  using  an exec messageport.  You can
  22. simply  send  messages  to  this  port to get informations about the actual
  23. status  f.e.   of the harddrives or set new parameter and so on.  If you do
  24. not  now how to use such a port, have a look in the RKRM`s and the included
  25. demosource  (GetStats.c).   It is written in C, but you should hopefully be
  26. able to understand this, even if you now little about C.
  27.  
  28. Now the real part:
  29.  
  30. The name of the port is "HDOFF_PORT"
  31.  
  32. Here is the structure for C :
  33.  
  34. NOTE the actual portversion is 100  (standing for 1.00)
  35.  
  36. NOTE also that HD_Reserved must be 0!
  37.  
  38. /****************************************************************************/
  39. /* The message-structure*/
  40.  struct HD {
  41.      struct  Message HD_Msg;
  42.      WORD    HD_Cmd;
  43.      UWORD   HD_TimeHD0;
  44.      UWORD   HD_TimeHD1;
  45.      UWORD   HD_TimeLeftHD0;
  46.      UWORD   HD_TimeLeftHD1;
  47.      BOOL    HD_StatHD0;
  48.      BOOL    HD_StatHD1;
  49.      ULONG   HD_PortVer;
  50.      LONG    HD_Reserved;
  51.      }
  52. /* define HDOff`s commands*/
  53. #define hd_GetStats     0x0
  54. #define hd_SetStats     0x1
  55. #define hd_Subscribe    0x2
  56. #define hd_Unsubscribe  0x3
  57. #define hd_StopDrive    0x4
  58. #define hd_Quit         0x5
  59. #define hd_ForceQuit    0x6
  60. #define hd_Die          0xFF
  61. /****************************************************************************/
  62.  
  63. And here the assemblerstructure:
  64.  
  65. /****************************************************************************/
  66.     STRUCTURE       HD,MN_SIZE
  67.         WORD    HD_Cmd
  68.         UWORD   HD_TimeHD0      ;Time in secs (startvalue)
  69.         UWORD   HD_TimeHD1
  70.         UWORD   HD_TimeLeftHD0  ;Time in secs (actual)
  71.         UWORD   HD_TimeLeftHD1
  72.         BOOL    HD_StatHD0      ;$ff(TRUE): Drive off
  73.         BOOL    HD_StatHD1
  74.         ULONG   HD_PortVer      ;Version of the port
  75.         LONG    HD_Reserved     ;reserved for future use! Set to 0!
  76.         LABEL   HD_SIZE
  77.  
  78. hd_GetStats     equ     $00
  79. hd_SetStats     equ     $01
  80. hd_Subscribe    equ     $02
  81. hd_Unsubscribe  equ     $03
  82. hd_StopDrive    equ     $04
  83. hd_Quit         equ     $05
  84. hd_ForceQuit    equ     $06
  85. hd_Die          equ     $FF
  86. /****************************************************************************/
  87.  
  88.  
  89. COMMAND DOCUMENTATION
  90.  
  91. hd_GetStats     equ     $00
  92. ~~~~~~~~~~~
  93. This gives you back the message filled with valid values.
  94.  
  95. hd_SetStats     equ     $01
  96. ~~~~~~~~~~~
  97. You  can  set  HD_TimeHD0 and HD_TimeHD1 to new values, and you will get an
  98. answer like hd_GetStats.  This means, you have to initalize HD_TimeHDx with
  99. the  number  of seconds(!) you want and PutMsg() it.  HDOff reset`s now its
  100. internal timecounters to your values.
  101.  
  102. hd_Subscribe    equ     $02
  103. ~~~~~~~~~~~~
  104. If  you  subscribe,  you  will  get  a  message  everytime a drive has been
  105. switched  on/off.   Check  the  answer!   If  HD_Cmd=0 your subscribing was
  106. unsuccessfull.
  107.  
  108. If  a drive changed its status, you`ll get a messy with HD_Cmd=hd_Subscribe
  109. filled  with the new datas.  You must not change/reply or do something else
  110. with this messy (except reading it out, of course ;) !
  111.  
  112. hd_Unsubscribe  equ     $03
  113. ~~~~~~~~~~~~~~
  114. You  won`t get a messys on a drive power down/up any more.  If HD_Cmd=0 you
  115. weren`t subscribed :)
  116.  
  117. hd_StopDrive    equ     $04
  118. ~~~~~~~~~~~~
  119. Here you can switch a drive off by setting HD_StatHDx to 0xff.
  120.  
  121. hd_Quit         equ     $05
  122. ~~~~~~~
  123. This tries to terminate HDOff.  If the reply has HD_Cmd=hd_Die quitting was
  124. successfull, if not not :)
  125.  
  126. hd_ForceQuit    equ     $06
  127. ~~~~~~~~~~~~
  128. The same as hd_Quit, but using the force option (can`t fail), and you won`t
  129. get a reply.  NOTE:  read the warning about the FORCE-option in the doc!
  130.  
  131. hd_Die          equ     $FF
  132. ~~~~~~
  133. NOTE:  you can _only_ recive this!  If you get this Message, HDOff has been
  134. terminated and you must stop using the port any longer!  (You will only get
  135. this if you subscribed).
  136.  
  137.  
  138. EXAMPLE
  139.  
  140. If  you  want, have a look in GetStats.c.  It shows you how to deal with an
  141. exec port and how to use the hd_GetStats command.
  142.  
  143.  
  144. HISTORY
  145.     v1.0 - extremly quick&dirty docs about the port
  146.     v1.1 - Reformated the text and added the C informations
  147.